<?php
/**
 * Here all global framework interfaces are defined.
 *
 * @category   UniKap-Framework
 * @package    Core
 * @subpackage Interfaces
 * @author     Ulf -UniKado- Kadner <ulfikado@gmail.com>
 * @since      2014-03-29 16:17
 * @version    0.1
 */

namespace UF
{

    # <editor-fold defaultstate="collapsed" desc="\UF\IToStringConverter">

    /**
     * If a object inside the Framework can be casted to a string so its already implements this interface.
     *
     * @since   v0.1
     */
    interface IToStringConverter
    {

        /**
         * Returns the string, associated with the current instance data.
         *
         * @return string
         * @since   v0.1
         */
        public function __toString();

    }

    # </editor-fold>

    # <editor-fold defaultstate="collapsed" desc="\UF\IFromStringConverter">

    /**
     * If a framework object can be initalized from a string, so it must implement this interface.
     *
     * @since   v0.1
     */
    interface IFromStringConverter
    {

        /**
         * Inits the object instance data from the defined string.
         *
         * This method must can handle strings producted by toString().
         *
         * @param  string $str The string with the objects instance data, to parse
         * @return boolean
         * @since   v0.1
         */
        public function fromString( $str );

    }

    # </editor-fold>

    # <editor-fold defaultstate="collapsed" desc="\UF\IStringConverter">

    /**
     * If a framework object can be initalized from a string, and convertet to a string it must implement this
     * interface. It merges {@see \UF\IToStringConverter} and {@see \UF\IFromStringConverter}.
     *
     * @since   v0.1
     */
    interface IStringConverter extends \UF\IToStringConverter, \UF\IFromStringConverter {}

    # </editor-fold>

    # <editor-fold defaultstate="collapsed" desc="\UF\IEquatable">

    /**
     * If a framework object can be equaled with a other object, so it must implement this interface.
     *
     * @since   v0.1
     */
    interface IEquatable
    {

        /**
         * Inits the object instance data from the defined string.
         *
         * This method must can handle strings producted by toString().
         *
         * @param  miced $value The othe element to equal with.
         * @param  boolean $strict Allow only values of current type? (Defaults to FALSE)
         * @since   v0.1
         */
        public function equals( $value, $strict = false );

    }

    # </editor-fold>

    # <editor-fold defaultstate="collapsed" desc="\UF\IArrayConverter">

    /**
     * If a framework object can be converted from an to a array, so it must implement this interface.
     *
     * @since   v0.1
     */
    interface IArrayConverter
    {

        /**
         * Returns the whole instance data as a associative array.
         *
         * @return array A Array with the data of the implementing instance.
         * @since  v0.1
         */
        public function toArray();

        /**
         * Changes the data of current instance to the data from $objectData.
         *
         * @param  array $objectData Associative Array
         * @return boolean
         * @since  v0.1
         */
        public function fromArray( array $objectData );

    }

    # </editor-fold>

    # <editor-fold defaultstate="collapsed" desc="\UF\IXmlConverter">

    /**
     * If a framework object can be converted from an to XML, so it must implement this interface.
     *
     * @since   v0.1
     */
    interface IXmlConverter
    {

        /**
         * Writes all instancedata to the defined XmlWriter.
         *
         * @param  \XmlWriter $w The XmlWriter
         * @param  string $elementName The Name of the element to create
         * @since  v0.1
         */
        public function writeXML( \XmlWriter $w, $elementName );

        /**
         * Reads the instance data from defined XML element.
         *
         * @param  \SimpleXMLElement $xmlElement The XML element that defines the instance data.
         * @return boolean
         * @since  v0.1
         */
        public function readXML( \SimpleXMLElement $xmlElement );

    }

    # </editor-fold>

    # <editor-fold defaultstate="collapsed" desc="STATIC CLASS '\UF\InterfaceHelper'">

    /**
     * This class defines some static helper functions for checking if a class implements one of the framework
     * core interfaces.
     *
     * @since   v0.1
     */
    class InterfaceHelper
    {

        # <editor-fold defaultstate="collapsed" desc="H I D D E N   C O N S T R U C T O R">

        private function __construct() { }

        # </editor-fold>

        # <editor-fold defaultstate="collapsed" desc="- - - -   P U B L I C   S T A T I C   M E T H O D S   - - - - - - - - - - - - - -">

        /**
         * Checks if a objects class implements {@see \UF\IToStringConverter} and {@see \UF\IFromStringConverter}
         *
         * @param  object $value
         * @return boolean
         * @since  v0.1
         */
        public static function IsStringConverter( $value )
        {
            if ( \is_null( $value ) ) return false;
            return ( $value instanceof \UF\IToStringConverter ) &&
                   ( $value instanceof \UF\IFromStringConverter );
        }

        /**
         * Checks if a objects class implements {@see \UF\IFromStringConverter}
         *
         * @param  object $value
         * @return boolean
         * @since  v0.1
         */
        public static function IsFromStringConverter( $value )
        {
            if ( \is_null( $value ) ) return false;
            return ( $value instanceof \UF\IFromStringConverter );
        }

        /**
         * Checks if a objects class implements {@see \UF\IToStringConverter}
         *
         * @param  object $value
         * @return boolean
         * @since  v0.1
         */
        public static function IsToStringConverter( $value )
        {
            if ( \is_null( $value ) ) return false;
            return ( $value instanceof \UF\IToStringConverter );
        }

        /**
         * Checks if a objects class implements {@see \UF\IArrayConverter}
         *
         * @param  object $value
         * @return boolean
         * @since  v0.1
         */
        public static function IsArrayConverter( $value )
        {
            if ( \is_null( $value ) ) return false;
            return ( $value instanceof \UF\IArrayConverter );
        }

        /**
         * Checks if a objects class implements {@see \UF\IXmlConverter}
         *
         * @param  object $value
         * @return boolean
         * @since  v0.1
         */
        public static function IsXmlConverter( $value )
        {
            if ( \is_null( $value ) ) return false;
            return ( $value instanceof \UF\IXmlConverter );
        }

        # </editor-fold>

    }

    # </editor-fold>

}

